This document is intended to provide ACE! developers with a summary of the changes to the Development documentation in each new version, so as to avoid the need to re-read the documentation again just to find the new information.
Please be sure to check the ACE web page (see the "Read Me") for bug reports and updates.
ACE version 1.7.2
A modules 'ACEm' resource no longer needs a name. The filename of the module now determines the name that appears in the module menu. You can still give the 'ACEm' resource a name to ensure backwards compatibility with pre 1.7.2 versions of ACE.
A new startup option has been added that allows error text and id's to be written to a log file. See the "Startup Options" section of "Development (part I)" for more information.
ACE version 1.7.1
A new field has been added to the 'ACEm' resource which allows for additional file filtering by file name or by file extension. Also, a wildcard parameter can be used to specify the document type. See the 'ACEm' section of "Development (part II)" for more information. These modifications has changed the format of the 'ACEm' resource.
ACE version 1.7
ACE can now open multiple resources in multiple windows (previously, only the data fork or a single resource could be opened into multiple windows). The "Pool of Radiance" module uses this feature. To achieve this, some fields of the 'ACEm' resource have extra functionality. See the 'ACE module resources' section of "Development (part II)" for more information.
ACE version 1.6.2
This release adds no new developer features.
ACE version 1.6.1
Script file names, 'scpt' resource names, and 'ACEm' resource names can now include the characters ; ^ ! < / ( and -. Previously, these characters could not be used. Note that if you do use one or more of these characters, be sure to indicate that your module is not compatible with previous versions of ACE via the appropriate 'ACEv' resources.
ACE version 1.6
In previous versions of ACE, the first slot in a compound file was assumed to contain a pc. In this version of ACE, the first slot is tested for the presence of a pc in the same way as all subsequent slots. This feature is used in the 'Heroes of Might & Magic II' module to display only the heroes that are in the game.
ACE will now correctly handle the situation where both equations in STR#138 are used simultaneously (previous versions would not).
The maximum number of windows that can be open has been reduced to 40 again (see above).
The 'Required Suite' of scripting commands is now displayed correctly with all versions of AppleScript. The quit and close commands have optional parameters that specify whether a window should have any changes saved automatically ('yes' or 'no'), or whether the user should be prompted ('ask'). You can change the current module via a script by setting the module property of the application. The optional parameter for the save command has been renamed as 'in'. The dictionary is also better documented.
A section on recordability has been added to "Development (Scripting)".
ACE version 1.5.1
A pop-up menu control can now be linked to a list so that when the selected menu item changes, the list can change the string resource used to display it's items. The Realmz, M&M II and M&M III modules use this feature to link the character's class to the list of spells. This is the first step in a more general system of control linking, and is described in the new section on Control Linking in "Development (part III)" and in "Development (Lists)".
Removed the section 'Script Errors' from "Development (Scripting)" as it was erroneous: A script error is automatically signaled to ACE when it occurs, and there is currently no way to change this. A result of this is that if the user clicks the cancel button in a 'choose from list' dialog, ACE will report this as an error.
In the user documentation, the dialogs that the user edits files with are now consistently called 'windows', and a note explaining this has been added to the 'DITL' section of "Development (part II)".
ACE version 1.5
Lists and their contents (cells) can now be scripted. Refer to "Development (Scripting)" for more details.
The format of the 'ACEm' resource has been changed (and simplified). The old format is incompatible with ACE version 1.4.1 and earlier. You will need to use the new 'ACEm' template to edit 'ACEm' resources. See the section on the 'ACEm' resource in "Development (part II)" for more information.
The maximum number of open windows has been increased to 55 to accommodate the rather extreme case of Heroes of Might & Magic II - Heroes.
All embedded scripts are now saved as 'run-only'. This reduces the size of the scripts by 3 or 4 times, but makes it impossible to view embedded scripts in the script editor. If you want to see how a particular script works, contact me and I'll forward you an editable version.
Fixed a couple of scripting bugs: The first involved getting and setting the index property of a window. The second was the omission of the index parameter of a control.
The offset examples in Appendix D were out of date and incorrect. They have been updated.
The equation that stopped ACE looking for any further pc's in a file (STR#138, id 2) did not work correctly. This feature was introduced in ACE version 1.4.1, but was not used in any modules (but in this version of ACE, the Jewel of Arabia modules make use of this feature).
When using an equation to determine if an extra pc is at a given offset in a file, the offset of the ten bytes to be examined can now be specified (in version 1.4.1, the first 10 bytes were used). This is specified in the 'Extra Pc Equation Offset' field of the 'ACEm' resource. As of version 1.5, ACE will not read the 'No extra Pc byte' field used in old modules (modules that still use this field will generate an error when trying to open a save game).
ACE! version 1.4.1
Two minor changes have been made to ACE in this version. ACE version 1.4.1 is still completely backwards compatible with modules from version 1.4, but any module exploiting these new features will obviously not work with ACE 1.4 or earlier.
1. A better method for determining the position of characters in compound files has been added. Instead of using a single byte (the 'No extra Pc byte' field of the 'ACEm' resource), the presence of a character at the given offset can be determined using an equation. This is documented more fully in the "Pc in own file" section of the documentation for the 'ACEm' resource, in "Development (part II)". The 'No extra Pc byte' field of the 'ACEm' resource has been removed, but ACE will still read from this field in an old (pre 1.4.1) module.
2. A control that changes the document type (determined by the 'file type control' field of the 'ACEm' resource) can now have it's value parsed by an equation first. The equation is located in the STR#139 resource, id 1. If this resource is not present, the control value is used directly (this was the original method). The "Realmz" module makes use of this new feature to change the character file icon when the character's caste is changed. The documentation in the 'file type control' section of the documentation for the 'ACEm' resource, in "Development (part II)" has been updated to reflect these changes.
A section explaining simple and compound files has been added to "Development (part I)".
ACE! version 1.4
The most significant update to ACE! in this version is addition of lists, which are used to edit equipment, spells etc. The documentation is in "Development (Lists)".
The 'Utilities' section of the Development documentation (part 1) has been updated. Of particular note is the new version of HexEdit by Lane Roathe which has a file comparison feature.
For tabbed windows, it is no longer necessary to create a entire new set of dialog panes if you want to use any appearance manager specific controls (as per ACE! 1.3). You can now create appearance manager specific panes on a pane-by-pane basis. See the 'Tabbed Window Implementation' section of "Development (Tabs)" for more information.
The "Data offset (from start)" field of the 'ACEm' resource now works slightly differently. Previously, offsets in 'ACEc' resources were not measured relative to the "Data offset (from start)" field. They are now measured relative to this offset.
The "Data offset (from start)" field of the 'ACEm' resource can now specify a negative offset. This allows you to use the "Data offset (from this)" field to search for data which is past the save game data, then move back to the save game data. The "Abuse" module uses this technique. The documentation for the 'ACEm' resource in "Development (part II)" has been updated to reflect this change.
The "No extra Pc byte" field of the 'ACEm' was incorrectly documented. The documentation for the 'ACEm' resource of the "Development (part II)" document has been updated to correct this.
You can turn off the appearance manager in ACE! to allow you to test lists in non-appearance mode. Immediately after opening ACE in the Finder, hold down the option key until you see a dialog appear. See "Development (III)" for more information.
It is no longer necessary to use a resource editor to name the 'scpt' resource for a script which resides in the "Script" folder. This process is still necessary for scripts embedded in modules.
The note on ResEdit bugs in the "Version Info" document have been modified and expanded. In particular, two bugs that occur only with MacOS 8.5 have been added.
ACE! version 1.3
The major new feature of this version is tabbed windows. The use of tabbed windows is a user option, so a non-tabbed window must also be included. The new control types are documented in "Development (Tabs)", Appendix G, and in the section on the 'CNTL' resource in "Development (II)".
ACE can now open 40 windows simultaneously, instead of only 16. To accommodate this and the larger dialogs, the preferred memory allocation has been raised to 1.5 megs.
The ACE templates contain a new template for editing the 'tab#' resource.
The Link fields of a 'ACEc' resource now specify control numbers, not dialog item id's.
You can now use the optional 'to' parameter of the save script command. This allows you to save the window to a new file (equivalent to the user choosing Save A Copy As from the File menu).
Changes to the internal workings of ACE! mean that modules designed for ACE! version 1.2.1 and earlier will not work with ACE! 1.3. Likewise, earlier versions of ACE! cannot use modules designed for ACE! version 1.3, even if they do not use multi-pane dialogs. You will need to change your modules 'ACEv' resources to reflect this.
The minimum requirements to convert an existing module to work with ACE 1.3 are:
1. Add a 'ACEv' resource id 121.
2. Set all (3) 'ACEv' resources to false.
3. Change the 'dlgx' resource from 0000 0000 000D to 0000 0000 000F (this enables the control hierarchy)
4. Modify the 'vers' id 128 resource so that it's version field reads 1.3.0
If your appearance manager savvy dialog (id 129) contains group box controls, you will need to change the numbering of the dialog items and add a 'ACEi' resource. See "Development (III)" for more information.
ACE! version 1.2.1
This release adds no new developer features. However, because it is a new version, a new 'ACEv' resource is necessary in modules designed for ACE! 1.2.1. For more information, see below, and also the section on the 'ACEv' resource in the "Development (part II)" document.
ACE! version 1.2
The major new feature in this version of ACE! is scriptability. You can script ACE! with any OSA language. See the "Development (Scripting)" document for more information.
You can now specify 'any' application in the 'ACEm' resource (achieved with an application type of '****'). The application type will be ignored when searching for files which can be opened by the current module. The Omega 0.75 module makes use of this. See the section on the 'ACEm' resource in the development documentation for more information.
It is now necessary to create an 'ACEv' resource when developing a module. For more information, see below, and also the section on the 'ACEv' resource in the "Development (part II)" document.
ACE! version 1.1.1
ACE! now has the ability to determine if a module made for a newer version of ACE! will work with an older version. This is achieved by reading 'ACEv' resources in the module, which simply indicate if the module is compatible with that version of ACE (specifically, it looks for a resource id equal to the application version).
Because version 1.1.1 is the first version to read 'ACEv' resources, it is not necessary to create these resources for modules designed for version 1.1.1. Only in the next version of ACE! will 'ACEv' resources become useful.
A new chapter has been added to the Appendices regarding backwards compatibility, and this will be updated with each new version of ACE. Based on the features used in your module, you will be able to determine what versions of ACE it will (or won't) work with.
To summarise version checking:
• If the module is designed for the current version of ACE, it's ok.
• If the module is designed for an older version of ACE, the ACE application will know whether it is compatible or not and alert the user if necessary.
• If the module is designed for a newer version of ACE, the ACE application will look for an 'ACEv' resources to determine if it is compatible or not and alert the user if necessary.
ACE! version 1.1
The major enhancement to this version is "theme-savyness". ACE! hooks into the Appearance manager (in MacOS 8, or Kaleidoscope/Aaron in System 7.x/MacOS 8) and uses it to draw it's dialogs and alerts, and also the module dialogs. ACE! is still completely compatible with non-appearance manager (MacOS 7.x) systems, as are modules designed for ACE! 1.1. Modules made for version 1.0 of ACE! will work with ACE! 1.1, although they will not be "theme-savy".
The changes required to support the Appearance manager (hereafter A.M.) in a module are minimal. Currently, the only new A.M controls supported are the new group box and separator lines. These are implemented as controls (use a 'CNTL' resource id 2000+ for each). Refer to an existing module or the "Module format" section of the development documentation for more information on A.M. group boxes.
If your module does not use any group boxes or separator lines, all you need to do is add a 'dlgx' resource (copy the one provided with the module template), but make sure it's id is 128, not 129. It is not necessary to edit the contents of this resource.
If you want to use the new group boxes/separator lines, you will need to duplicate the 'DITL' id 128. The new 'DITL' (id must be 129) is used if the A.M is present. You can then delete the group boxes/separator lines from 'DITL' 129 and add the new ones. You will need to add another 'DLOG' resource (duplicate the existing one) with id 129. Edit it so that it refers to 'DITL' 129 and not 128. You do not need to change the dialog colours - leave them as the default. Add a 'dlgx' resource (id 129).
Lastly, update your 'vers' id 128 resource to refer to version 1.1. You can update your 'vers' id 1 resource as appropriate.
Note: The comments on the problems experienced by ResEdit with pop-up menu controls also apply to group box/separator line controls (in fact, any type of control). You may see group boxes loose their title, or go gray. If his happens, save and quit immediately, then reopen ResEdit.
